.\" $Id: PAPI_query_event.3,v 1.14 2004/10/01 18:19:49 you Exp $
.TH PAPI_query_event 3 "September, 2004" "PAPI Programmer's Reference" "PAPI"

.SH NAME
.nf
PAPI_query_event \- query if PAPI event exists
.fi

.SH SYNOPSIS
.B C Interface
.nf
.B #include <papi.h>
.BI "int PAPI_query_event(int " EventCode ");"
.fi
.B Fortran Interface
.nf
.B #include "fpapi.h"
.BI PAPIF_query_event(C_INT\  EventCode,\  C_INT\  check )
.fi

.SH DESCRIPTION
.B "PAPI_query_event()"
asks the PAPI library if the PAPI Preset event can be counted on this
architecture. If the event CAN be counted, the function returns
PAPI_OK.  If the event CANNOT be counted, the function returns an
error code.  This function also can be used to
check the syntax of a native event.

.SH ARGUMENTS
.I EventCode
-- a defined event such as PAPI_TOT_INS.
.LP

.SH RETURN VALUES
On success, 
.B PAPI_query_event returns
.B "PAPI_OK" 
 On error, a non-zero error code is returned.


.SH ERRORS
.TP
.B "PAPI_EINVAL"
One or more of the arguments is invalid.
.TP
.B "PAPI_ENOTPRESET"
The hardware event specified is not a valid PAPI preset. 
.TP
.B "PAPI_ENOEVNT"
The PAPI preset is not available on the underlying hardware. 

.SH EXAMPLES
.nf
.if t .ft CW
int retval;

/* Initialize the library */

retval = PAPI_library_init(PAPI_VER_CURRENT);

if (retval != PAPI_VER_CURRENT) {
  fprintf(stderr,"PAPI library init error!\\n");
  exit(1); }
	
if (PAPI_query_event(PAPI_TOT_INS) != PAPI_OK) {
  fprintf(stderr,"No instruction counter? How lame.\\n");
  exit(1);
  }
	
.if t .ft P
.fi

.SH BUGS
These functions have no known bugs.

.SH SEE ALSO
.BR PAPI_preset "(3), " PAPI_native "(3), "
.BR PAPI_remove_event "(3), " 
.BR PAPI_remove_events "(3), "

